Back to Main Menu

Create Work Order

Introduction

The REST API /api/v2/workorder is used to POST a new work order.

The work order can be created at any stage in the workflow (i.e status). Depending on the Status at which the work order is created, the mandatory parameters will vary.

The role that should be used with this API is "Mnt Admin"

Required Properties

The table below outlines the required properties (fields) for each stage of the workflow based on the status that the work order is being created at. Note that 'Status' is always mandatory.

An '✔' represents a mandatory property, and an '✓' represents a conditional mandatory property.

✓1 - Depending on WorkOrderType this property is required. Refer to "WorkOrderType and Failure/Cause/Remedy Codes" below

✔2 - Refer to MaintenanceResources below for further detail.

Additional Properties

In addition to the properties above, the table below lists some additional properties that whilst not mandatory are typically used when creating a work order

Field Details

Asset ID

This is the Asset ID of the asset to be assigned to the work order. Note that it is the asset internal ID (GUID) and not the user friendly asset ID presented to the user. Use the API GET /api/v2/assets/{id} to get the Id by its user friendly asset ID.

Priority

The Priority is an integer in the range 1-5 that matches the integer displayed in the Priority selection list in Brightly Assetic. The description for the code is configurable at a site level. More than one Priority list may be defined for a site (aligned with Asset Type), so it cannot be assumed that a given Priority ID has the same meaning for different asset types.

EstimatedDuration

EstimatedDuration is an decimal number representing the number of hours the work order is expected hours to take to resolve. It must be greater than the hours assigned to crafts in the tasks.

WorkOrderType and Failure/Cause/Remedy Codes

The WorkOrderType is mandatory. It also influences whether FCR (Failure/Cause/Remedy) codes are required.

The Assetic REST API endpoint GET /api/v2/worktype gets the list of work types and whether Failure, Cause, and Remedy Code is required.

https://[yoursite]/api/v2/worktype 

Sample WorkType Response

The following sample response shows the information returned by GET /api/v2/worktype.

• "Id" is the value used for the WorkOrderType Id property when creating a work order.

• "IsFailureRequired', "IsCauseRequired", and "IsRemedyRequired" indicate for the chosen worktype whether FailureSubCodeId, CauseSubCodeId, and RemedyCodeId respectively are required.

{   "TotalResults": 12,   "TotalPages": 1,   "Page": 1,   "ResourceList": [     {       "Id": 1,       "Name": "Preventive Maintenance",       "Code": "PM - Periodic",       "BudgetType": "OPEX",       "Description": "Periodic maintenance to prevent technical failure of asset",       "IsFailureRequired": false,       "IsCauseRequired": false,       "IsRemedyRequired": true,       "_links": [],       "_embedded": null     },     .....

Get FCR Codes

The REST API GET /api/v2/fcrcategorisation is used to get the list of configured FCR codes as per sample request below:

https://[YourDomain].assetic.net/api/v2/fcrcategorisation

The response is an array of FCR definitions, so firstly choose the FCR definition that will be used.  Within that definition is 'CauseCodes', 'FailureCodes' and 'RemedyCodes':

• CauseCodes - This is the list of Cause Codes.  The "Description" is what is displayed in the application when choosing a Cause.  Each 'Cause' has a 'Sub Cause', which is what is chosen when creating a work order
•  CauseSubCode - The sub codes within a cause are listed in the response.  Use the value for 'Id' and not 'SubCodeNumber'
• FailureCode - This is the list of Failure Codes.  The "Description" is what is displayed in the application when choosing a Failure.  Each 'Failure' has a 'Sub Failure', which is what is chosen when creating a work order
  •  FailureSubCode - The sub codes within a failureare listed in the response.  Use the value for 'Id' and not 'SubCodeNumber'
• RemedyCodes- This is the list of Remedies.  The "Description" is what is displayed in the application when choosing a Remedy.  There is no 'Sub Remedy', so use the value for 'Id' when creating a work order.

RequestorId and CreatorId

• RequestorId represents the Assetic resource to be recognised as requesting the work order be created.
• CreatorId represents the Assetic resource to be recognised as the source or creator of the work order.  It would typically be the user creating the work order.

For both of these properties, the Id used is the 'Resource Id'  (a GUID) from the Assetic resource list.  Note that it is not the user login Id.  Typically when a resource is created, that resource is linked to a login.  Using the Assetic REST API endpoint GET /api/v2/auth the resource Id of the user authenticated to the REST API is returned as part of the response.

The Assetic REST API GET /api/v2/resource may be used to get the resource GUID using the resource name as the search criteria.  For more detail refer to the article Get Resources.

The Requestor must be a resource of Type "Employee" or be linked to an Assetic login ("user").  The API will return an error if the Requestor Resource type is not valid.

Dates

Dates are defined in the "Scheduling" property which is an object of type "MaintenanceScheduling". The date properties within "MaintenanceScheduling" are of type datetime.

TargetStart is a mandatory field in all instances

TargetFinish is not mandatory.  If omitted it will be calculated based on the response times defined in the priority matrix, using the date & time of the API integration as the starting point to apply (the target start date is not used as the response time starting point)

ScheduledStart and ScheduledFinish are mandatory for some statuses as indicated in the table above.  In addition, they must be greater than the current date/time where status = "RFE"

Responsible Officer

As per RequestorId and CreatorId, the ResponsibleOfficerId is the 'Resource Id'  (a GUID) from the Assetic resource list.

The Resource Type of the selected resource must be one of "Contractor","Employee" or "Company",  or be linked to an Assetic login ("user") otherwise an error will be returned by the API.

Labour

The Labours property is an array of 'Labour' objects.

For the status "PREP" the "Labours" property must be included in the payload as an array (possibly empty).  At all other statuses the array must have at least one 'Labour' object.

Within the Labour object are the following properties:

The Assetic REST API GET /api/v2/resource/{id}/craft is used to get a list of GroupCraftId's available to use for PlannedGroupCraftId.  {id} is the Resource GUID of the labour resource that will be assigned.  There may be multiple GroupCrafts for the resource based on Workgroup and Craft.

MaintenanceResources

MaintenanceResources is an array of objects of type MaintenanceResource

The following table lists the properties within MaintenanceResource

AssignedGroupCraftId used the GroupCraftId returned by the Assetic REST API GET /api/v2/resource/{id}/craft (as described above)

Resource Status

The following table lists the options for the status property in the MaintenanceResource object:

RsResourceRepresentation

The only property required is "Id" which is the GUID of the of the resource (person/organisation) to be assigned to the labour item. 

The Assetic REST API GET /api/v2/resource may be used to get the resource GUID using the resource name as the search criteria.  For more detail refer to the article Get Resources.

MaintenanceMaterials

The MaintenanceMaterials property is an array of objects of type MaintenanceMaterial.  It is used to assign materials to the work order.  Materials are optional for inclusion at all statuses.

If there are no MaintenanceMaterials, this property needs to be included in the POST payload as an empty array.

Use the Assetic REST API GET /api/v2/billofmaterial to get the GUID of the material

The following table lists the properties within MaintenanceMaterial object:

The 'Availability' of the material may be set via the property IsMaterialAvailable.  The following options exist.

If TRUE then it indicates the assigned materials are available (in stock).  If FALSE then the materials are not available.  Does not allow work order progression beyond WMATL status.

MaintenanceServices

The MaintenanceServices property is an array of objects of type MaintenanceService.  It is used to assign services to the work order.  Services are optional for inclusion at all statuses.

If there are no Maintenance Services, this property needs to be included in the POST payload as an empty array.

Use the Assetic REST API GET /api/v2/serviceactivity to get the GUID of the Service Activity

The following table lists the properties within MaintenanceService object:

The list of UnitType names is available via the REST API GET /api/v2/unittype.

ExternalId

This is a hidden field that can assist with integration by recording a string identifier that has meaning to an external system.

SupportingInformation

This property is an array of type SupportingInformation.  It allows notes to be recorded against the work order.

If there is no SupportingInformation, this property needs to be included in the POST payload as an empty array.

Otherwise, one or more notes may be created.

LocationDescription and PointString

The LocationDescription is mandatory.  It is a free text description of the defect location.

The PointString is the optional spatial point definition for the defect location. 

The point is a string formatted as longitude followed by latitude (EPSG:4326) separated by a whitespace.

In the example below the point is at longitude 144.96406820000004 and latitude -37.8162175.

The string is the value for the property "PointString"

"PointString": "144.96406820000004 -37.8162175"

WorkTasks

WorkTasks are an optional array of type WorkTask

The following table lists the properties within the WorkTask object

To assign Work Tasks to Labour, MaintenanceMaterial, or MaintenanceService as part of the initial work order create (POST) create an Id (type = GUID) and assign the Id to the "Id" property of the task, and the "LinkedWorkTaskId" property of the Labour, MaintenanceMaterial, or MaintenanceService.

The following table lists the options for the status property in the WorkTask object:

Linked Work Requests

One or more work requests with a minimum status of 'Approved' may be linked to the work order.

The GUID of the work request is used to define the work request to link to.

Including the following sample in the payload will link 2 work requests to the work order.

"LinkedWorkRequests": [
 {
 "ID": "f5650456-3248-4d46-8920-a7b1281c8028"
 },
 {
 "ID": "9564cdc8-067e-406d-bc14-556759e60f5c"
}]

Sample Payloads

The following is a sample JSON payload with the minimum mandatory fields for creating a work order with a status of 'PREP'

{ 	"Status": "PREP", 	"AssetId": "6216b184-62b0-e611-946c-06edd62954d7", 	"BriefDescription": "Potholes in Collins Street", 	"EstimatedDuration": 3, 	"LocationDescription": "257 Collins St, Melbourne VIC 3000, Australia", 	"PointString": "144.96406820000004 -37.8162175", 	"CreatorId": "36bee8ab-4e39-4f1d-b713-4eefa521fcd8", 	"RequestorId": "8d05ef3b-5da4-e511-9451-06edd62954d7", 	"WorkOrderType": { 		"Id": 6 	}, 	"FailureSubCodeId": 1, 	"CauseSubCodeId": 1, 	"RemedyCodeId": 3, 	"Scheduling": { 		"TargetStart": "2017-11-15T16:04:56" 	} } 

The following is a sample JSON payload for creating a work order with a status of 'INPRG'

{ 	"Status": "INPRG", 	"BriefDescription": "Potholes in Collins Street", 	"PriorityId": 5, 	"EstimatedDuration": 3, 	"LocationDescription": "257 Collins St, Melbourne VIC 3000, Australia", 	"PointString": "144.96406820000004 -37.8162175", 	"CreatorId": "36bee8ab-4e39-4f1d-b713-4eefa521fcd8", 	"RequestorId": "8d05ef3b-5da4-e511-9451-06edd62954d7", 	"WorkOrderType": { 		"Id": 6 	}, 	"FailureSubCodeId": 1, 	"CauseSubCodeId": 1, 	"RemedyCodeId": 3, 	"SupportingInformation": [], 	"MaintenanceMaterials": [], 	"MaintenanceServices": [], 	"AssetId": "6216b184-62b0-e611-946c-06edd62954d7", 	"WorkOrderWorkGroup": "Roads", 	"Labours": [{ 		"PlannedGroupCraftId": "5379a3df-feb1-e611-946c-06edd62954d7", 		"QuantityRequired": 1, 		"HoursRequired": 3, 		"MaintenanceResources": [{ 			"Resource": { 				"Id": "36bee8ab-4e39-4f1d-b713-4eefa521fcd8" 			}, 			"StatusId": 1, 			"AssignedGroupCraftId": "5379a3df-feb1-e611-946c-06edd62954d7" 		}] 	}], 	"Scheduling": { 		"TargetStart": "2017-11-15T16:04:56", 		"ScheduledStart": "2017-11-17T00:00:00", 		"ScheduledFinish": "2017-11-18T00:00:00" 	}, 	"MaintenanceMaterials": [{ 		"BillOfMaterialId": "f812d794-c152-e611-9467-06edd62954d7", 		"IsMaterialAvailable": true, 		"PlannedQuantity": 1 	}], 	"WorkTasks": [{ 		"FriendlyId": 10, 		"BriefDescription": "The task", 		"Status":1 	}], 	"MaintenanceServices": [{ 		"PlannedQuantity": 1, 		"PurchaseOrderNumber": "po123", 		"ServiceActivityId": "ab08efe6-b41e-4e60-8f7b-9ab4daaf6ecc", 		"PlannedUnitRate": 1000, 		"UnitType": "Each", 		"Description": "Maintenance Activities Used" 	}] } 

Work Order Attachments

On successful POST the GUID identifier of the created Work Order is contained within the 'Id' property of the request's response. This Work Order GUID can be used for additional follow-up API requests to the Assetic REST API in order to create and link documents against the Work Order.

This is achieved by supplying the Work Order's GUID for the 'ParentId' parameter, and by also providing the value "WorkOrder2" for the 'ParentType' parameter within a payload for a request to the POST/api/v2/document endpoint.

Additional information covering the construction of a payload Document request, and how to upload files using the Assetic REST API Documents endpoint is covered in the article Uploading Files.